home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / grafik / 3d & render tools / xpgs-2.5 / xpgs.txt < prev    next >
Text File  |  1996-07-16  |  37KB  |  1,145 lines
  1. This is an abridged and edited version of the man pages intended for VMS
  2. users:
  3.  
  4.   Copyright 1994 and 1995, 26th January.
  5.   By Peter Chang. All rights reserved.
  6.   peterc@a3.ph.man.ac.uk
  7.  
  8.  
  9.   Permission to use, copy, modify, distribute, and sell this software and its
  10.   documentation for any purpose is hereby granted without fee, provided that
  11.   the above copyright notice appear in all copies and that both that copy-
  12.   right notice and this permission notice appear in supporting documentation,
  13.   and that the name of the copyright holder not be used in advertising or
  14.   publicity pertaining to distribution of the software without specific,
  15.   written prior permission. The copyright holder makes no representations
  16.   about the suitability of this software for any purpose. It is provided "as
  17.   is" without express or implied warranty.
  18.  
  19.   The copyright holder disclaims all warranties with regard to this software,
  20.   including all implied warranties of merchantability and fitness, in no
  21.   event shall the copyright holder be liable for any special, indirect or
  22.   consequential damages or any damages whatsoever resulting from loss of use,
  23.   data or profits, whether in an action of contract, negligence or other tor-
  24.   tious action, arising out of or in connection with the use or performance
  25.   of this software.
  26.  
  27. =============================================================================
  28.  
  29. xpgs(6)                                      xpgs(6)
  30.  
  31. NAME
  32.   xpgs - a suite of programs to design, generate and animate SIRDS for the X
  33.   Window System, and output SIS or autostereograms in a variety of formats
  34.  
  35. SYNTAX
  36.  
  37.   xpgs [options] <polyh or xss file>
  38.  
  39. OVERVIEW
  40.  
  41.   SIRDS stands for Single-Image Random Dots Stereogram; other common terms
  42.   are RDS, SIS and autostereograms though these do not strictly apply to, or
  43.   imply, SIRDS.
  44.  
  45.   The theory of SIRDS and autostereograms can be found in many postings to
  46.   alt.3d (including a FAQ obtainable from
  47.   http://www.cs.waikato.ac.nz/~singlis/sirds.html) and comp.graphics, there
  48.   are also some books around which deal with the subject. Some information
  49.   can be obtained on RDS from Bela Julesz's book "Foundations of Cyclopean
  50.   Perceptions"; a more recent source of information is the paper by Thimbleby
  51.   et al called "Displaying 3D images: Algorithms for SIRDS", available from
  52.   Stuart Inglis (singlis@waikato.ac.nz); also there is a short article called
  53.   "Stereography and Autostereograms" by the author of this package which can
  54.   be found, along with a gallery and URL links to other WWW pages on SIRDS,
  55.   at http://h2.ph.man.ac.uk/gareth/sirds.html.    Further resources can be
  56.   found at the main SIRDS at ftp://katz.anu.edu.au/pub/stereograms/.
  57.  
  58.   In this suite of programs, we start with a description of a volume of space
  59.   using Cartesian coordinates to label the vertices of the objects within the
  60.   space and lists of the polygonal faces which define each object.  The coor-
  61.   dinate axes are defined as x - horizontal (right), y - vertical (upward)
  62.   and z - perpendicular to the screen (toward the viewer).
  63.  
  64.   With this description, two buffers are built using a method described in
  65.   the article mentioned above.
  66.  
  67.   There are two basic types of autostereograms, these differ in the way the
  68.   image is viewed. The two possibilities are wide-eyed (WE) and cross-eyed
  69.   (CE) viewing. For whatever reasons, some people find it much easier to look
  70.   at SIRDS cross-eyed though the vast majority learn to see them wide-eyed.
  71.  
  72.   The parameters of the programs are :-
  73.      VD = viewing distance from the screen or paper (300mm)
  74.      ES = eye separation (65mm)
  75.      OS = offset of coordinate origin into (or out of) screen or paper (150mm)
  76.   The background plane is set at the offset OS+OY, this can be changed with
  77.   the -background option.
  78.  
  79.   The default options are set to give a reasonable wide-eyed (WE) SIRDS of
  80.   the objects on top of a background plane.
  81.  
  82.  
  83.  
  84. STRUCTURE
  85.  
  86.   A layout of the suite's programs and associated data follows
  87.  
  88.      3d datasets
  89.           |
  90.           |
  91.           v
  92.       cvtopolyh    mkpolyh
  93.           |           |
  94.           |           |
  95.           |           |
  96.     /-------------------------\    paint package
  97.     |         |          |    ^
  98.     |  (.polyh)  |    (.polyh)  |    | (.p?m)
  99.     |         |          |    |
  100.     v         v          v    v
  101.       xss --------> xpgs -------> cvtoppm <------ mindimage
  102.     |  (.xss)    |           |   |   (.rle)
  103.     |         |        (.p?m) |   |
  104.     |         |           v   |
  105.     \-------------------> sisgen   \----------> vpgs
  106.            (.xss)     |      (.p?m)
  107.                  |
  108.                  |
  109.                  v
  110.                  xv
  111.  
  112.  
  113.   MindImage is a PC SIRDS generator, xv is the X11 graphics viewer. The data
  114.   files are differentiated by their name extensions given in parentheses.
  115.   Although not shown on the diagram, xss, vpgs and xpgs can save an image in
  116.   X11 bitmap (.xbm) format and vpgs and xpgs can also save an image as a
  117.   Postscript (.ps) file.
  118.  
  119. DATA FILES
  120.  
  121.   .polyh  We have incorporated one 3D data format into xpgs:
  122.  
  123.          AVS polyh - list of vertices and list of polygonal faces given
  124.          by indexed points.
  125.  
  126.       (There is a slight difference with the inclusion of an optional
  127.       comment line at the start of the file which begins with a hash
  128.       "#".)
  129.  
  130.       Additional objects can be converted into this format using the
  131.       cvtopolyh program, it is able to change X3d v2.0 .obj files, Wave-
  132.       front .obj files and another format .3ds (I can't remember what
  133.       program uses this). New objects defined by functions can be made
  134.       using mkpolyh.
  135.  
  136.       We have bundled some objects for you to try out - regular solids in
  137.       polyh format and a couple of objects converted from X3d v2.0
  138.       objects and Wavefront objects.
  139.  
  140.       More objects can be found at ftp://avalon.vislab.navy.mil/ or
  141.       its mirrors.
  142.  
  143.   .rle      This is MindImage's data format using a basic run length encoding
  144.       method with indexing.
  145.  
  146.   .p?m = .ppm and .pgm
  147.       These are the colour and grey-scale portable pixmap formats from
  148.       the PBM packages (NetPBM or PBMPlus).
  149.  
  150.   .xss      This is a simple description format of a scene made from multiple
  151.       polyh objects.
  152.  
  153.  
  154.  
  155.  
  156. DESCRIPTION
  157.   Xpgs is an X11 program that generates, animates and outputs SIRDS.  It
  158.   takes an .xss or a .polyh file and optional switches as its command line
  159.   arguments.
  160.  
  161.   Options
  162.  
  163.   All these options can be abbreviated to the least letters needed to make
  164.   the chosen option distinct.  The default values are given in parentheses.
  165.  
  166.   -display <display>
  167.       sets the X display name. By default it is the local host or that one
  168.       defined in the the logical DECW$DISPLAY.
  169.  
  170.   -geometry <geometry>
  171.       sets the X geometry. (770x476 or 720x445)
  172.  
  173.   -wait <delay>
  174.       specifies the delay between frames in milliseconds used during anima-
  175.       tion. (300)
  176.  
  177.   -frames <1-24>
  178.       gives the number of frames for xpgs to generate. (1)
  179.  
  180.       If xpgs was compiled with the XPGSUSEPM macro defined then the number
  181.       of frames of animation possible depends on the X server memory alloca-
  182.       tion, ie. the number of big Pixmaps it can support.  If your server
  183.       can't handle a large number then either give xpgs a smaller number of
  184.       frames, eg. "-f 3", or recompile xpgs without the -DXPGSUSEPM flag in
  185.       the Makefile (make.com or descrip.mms).  Note if you take the latter
  186.       option then the animation may not be as fast as using Pixmaps, the per-
  187.       formance depends on the X server.
  188.  
  189.   -background <b>
  190.       sets the background plane at z=b*OY. (-1.0)
  191.  
  192.   -reverse
  193.       sets xpgs to cater for crosseyed viewing, by default it caters for
  194.       wide-eyed viewing.
  195.  
  196.   -enlarge <ef>
  197.       specifies the enlargement of depth effect in the final image. (1.0)
  198.  
  199.   -mag <mf>
  200.       sets the magnification of the scene. (1.0)
  201.  
  202.   -paper <wxh>
  203.       specifies the size of array for Postscript output.
  204.  
  205.   -indicoff
  206.       turns off indicators in window (used to aid the viewing process).
  207.  
  208.   -zblines <zb>
  209.       sets the number of lines that each z-buffer will use. (256)
  210.  
  211.       This limits the internal size of all z-buffers used in the program
  212.       without affecting the size of the stereogram output. It should be used
  213.       only when memory constraints are more important than speed considera-
  214.       tions: the smaller the value is the slower the program will become.
  215.  
  216.   -DENSITY <0-255>
  217.       sets the density of black dots in the SIRDS. (127)
  218.  
  219.   -GREY <1,2,4,8>
  220.       sets the number of grey-scale bits used in Postscript output. (1)
  221.  
  222.   -SHIMMER
  223.       sets xpgs to the shimmer mode, to aid newbies.
  224.  
  225.   -help
  226.       prints a summary of command line options and returns to DCL.
  227.  
  228.   Once running, it will display a few parameters in the terminal window,
  229.   create a empty graphics window and start to generate the SIRDS(s). Each
  230.   frame will be shown in sequence as the program proceeds.  When finished,
  231.   the program displays the "all done" message and enters the pause mode.
  232.  
  233.   KEYS
  234.  
  235.  
  236.   With the mouse pointer within the boundaries of the graphics window, xpgs
  237.   will respond to a set of keypresses.
  238.  
  239.     q   quits the program.
  240.     h   pops up a help window.
  241.     a   changes the rotation axis randomly.
  242.     i   re-initialise all of the points.
  243.     p   toggles the pause mode on and off.
  244.     r   reverses the sequence of frames.
  245.   While paused:
  246.     c   saves the current frame in .xss format.
  247.     l   loads a new object.
  248.     o   reloads old file.
  249.     n   skips to the next frame.
  250.     s   saves the current frame as a Postscript file.
  251.     w   saves the current frame as a X11 bitmap.
  252.  
  253.   See xss(6) about mouse controls and popup dialogue windows.
  254.  
  255. FILES
  256.  
  257. BUGS
  258.  
  259.   If you find any bugs, please report them to one of the authors listed
  260.   below.
  261.  
  262. SEE ALSO
  263.  
  264.   cvtopolyh(6), cvtoppm(6), mkpolyh(6), sisgen(6), vpgs(6), xpgs(6) and
  265.   xss(6).
  266.  
  267. AUTHORS, COPYRIGHTS, AND WARNINGS
  268.  
  269.   Copyright 1994 and 1995, 26th January.
  270.   By Peter Chang and Gareth Richards. All rights reserved.
  271.   peterc@a3.ph.man.ac.uk
  272.   gareth@h1.ph.man.ac.uk
  273.   Version 2.5
  274.  
  275. =============================================================================
  276.  
  277. vpgs(6)                                      vpgs(6)
  278.  
  279. NAME
  280.   vpgs - a SIRDS viewer for the X Window System, using depth map data
  281.  
  282. SYNTAX
  283.  
  284.   vpgs [options] <p?m file>
  285.  
  286. DESCRIPTION
  287.   Vpgs is an X11 program that displays SIRDSs using data from depth maps
  288.   saved in the portable pixmap format, .pgm or .ppm.
  289.  
  290.   It takes an .p?m file and optional switches as its command line arguments.
  291.  
  292.   Options
  293.  
  294.  
  295.   All these options can be abbreviated to the least letters needed to make
  296.   the chosen option distinct.  The default values are given in parentheses.
  297.  
  298.   -display <display>
  299.       sets the X display name. By default it is the local host or that one
  300.       defined in the logical DECW$DISPLAY.
  301.  
  302.   -geometry <geometry>
  303.       sets the X geometry. Defaults to the depth map size.
  304.  
  305.   -background <b>
  306.       sets the background plane at z=b*OY. (-1.0)
  307.  
  308.   -reverse
  309.       sets vpgs to cater for crosseyed viewing, by default it caters for
  310.       wide-eyed viewing.
  311.  
  312.   -enlarge <ef>
  313.       specifies the enlargement of depth effect in the final image. (1.0)
  314.  
  315.   -step <XxY>
  316.       gives the steps vpgs uses to traverse the depth map, see sisgen(6).
  317.       (1x1)
  318.  
  319.   -paper <wxh>
  320.       specifies the size of array for Postscript output.
  321.  
  322.   -indicoff
  323.       turns off indicators in window (used to aid the viewing process).
  324.  
  325.   -zblines <zb>
  326.       sets the number of lines that each z-buffer will use, see xpgs(6).
  327.       (256)
  328.  
  329.   -DENSITY <0-255>
  330.       sets the density of black dots in the SIRDS. (127)
  331.  
  332.   -GREY <1,2,4,8>
  333.       sets the number of grey-scale bits used in Postscript output. (1)
  334.  
  335.   -help
  336.       prints a summary of command line options and returns to DCL.
  337.  
  338.   Once running, it will display a few parameters in the terminal window,
  339.   create a empty graphics window and start to generate the SIRDS. When fin-
  340.   ished, the program displays a "all done" message.
  341.  
  342.   When the window is re-sized, the SIRDS is regenerated.
  343.  
  344.   KEYS
  345.  
  346.  
  347.   With the mouse pointer within the boundaries of the graphics window, vpgs
  348.   will respond to a set of keypresses.
  349.  
  350.     q   quits the program.
  351.     h   pops up a help window.
  352.     l   loads a .p?m file.
  353.     o   reloads old file.
  354.     s   saves the frame as a Postscript file.
  355.     w   saves the frame as a X11 bitmap.
  356.  
  357.   See xss(6) about mouse controls and popup dialogue windows.
  358.  
  359. FILES
  360.  
  361. BUGS
  362.  
  363.   If you find any bugs, please report them to the author listed below.
  364.  
  365. SEE ALSO
  366.  
  367.   cvtopolyh(6), cvtoppm(6), mkpolyh(6), sisgen(6), vpgs(6), xpgs(6) and
  368.   xss(6).
  369.  
  370. AUTHOR, COPYRIGHTS, AND WARNINGS
  371.  
  372.   Copyright 1994 and 1995, 26th January.
  373.   By Peter Chang. All rights reserved.
  374.   peterc@a3.ph.man.ac.uk
  375.   Version 2.5
  376.  
  377. =============================================================================
  378.  
  379. sisgen(6)                                sisgen(6)
  380.  
  381. NAME
  382.   sisgen - a program to generate and output a SIS
  383.  
  384. SYNTAX
  385.  
  386.   sisgen [options] <input xss or p?m file>
  387.  
  388. DESCRIPTION
  389.   Sisgen is a program that generates SISs. It can make random tiles or use a
  390.   tile given in the portable bitmap format .pgm or .ppm.
  391.  
  392.   It takes an .xss file or a .polyh file as the 3D input data or alterna-
  393.   tively a .p?m file as the depth map and optional switches as its command
  394.   line arguments.
  395.  
  396.   Options
  397.  
  398.  
  399.   All these options can be abbreviated to the least letters needed to make
  400.   the chosen option distinct.  The default values are given in parentheses.
  401.  
  402.   -geometry <wxh>
  403.       sets the picture geometry, this defaults to the values given if the
  404.       input is 3D data otherwise it defaults to the depth map size. (770x476
  405.       or 720x445)
  406.  
  407.   -background <b>
  408.       sets the background plane z=b*OY. (-1.0)
  409.  
  410.   -reverse
  411.       sets sisgen to cater for crosseyed viewing, by default it caters for
  412.       wide-eyed viewing.
  413.  
  414.   -enlarge <ef>
  415.       specifies the enlargement of depth effect in the final image. (1.0)
  416.  
  417.   -mag <mf>
  418.       sets the magnification of the scene, only applies to 3D data. (1.0)
  419.  
  420.   -pmm <res>
  421.       sets the dots' resolution in units of pixels per millimetre. (4.0)
  422.  
  423.   -fine <0-8> <tol>
  424.       sets the smoothing factors which sisgen uses for colour interpolation.
  425.       (0 1)
  426.  
  427.       Sisgen uses buffers which are integer based. So for smoother stereo-
  428.       grams, the numbers are scaled up by powers of two. In finding hidden
  429.       surfaces in the stereogram, the integers in the buffers are compared
  430.       and, if found with a certain range of each other, a point is considered
  431.       visible.
  432.  
  433.  
  434.       The first parameter is the multiplying factor in powers of two, whilst
  435.       the second gives the maximum absolute difference of values found in the
  436.       hidden surface check.
  437.  
  438.       For example, "-fine 2 7" means the numbers are first multiplied by 4
  439.       (2^2) and if found to have an absolute difference less than or equal to
  440.       7 then the corresponding point is visible.
  441.  
  442.   -tile <0-8>
  443.       sets the tiling method to use. (0)
  444.  
  445.       In all, sisgen allows nine different methods of using a tile to make a
  446.       SIS.
  447.  
  448.       Leave tile as it is and
  449.  
  450.       0  start from left
  451.       1  start from centre
  452.       2  start from right
  453.  
  454.       Scale the tile to fit on the background plane and
  455.  
  456.       3  start from left
  457.       4  start from centre
  458.       5  start from right
  459.  
  460.       Scale each line from the tile to fit the deepest plane that contains a
  461.       point on that line and
  462.  
  463.       6  start from left
  464.       7  start from the point in question
  465.       8  start from right
  466.  
  467.   -image <pxm file>
  468.       gives the name of the tile to be used in making the autostereogram.
  469.  
  470.   -xss
  471.       signifies that the input file contains 3D data and is either an .xss or
  472.       a .polyh file. This is the default.
  473.  
  474.   -dmap
  475.       signifies that the input file contains a depth map and is a grey-scale
  476.       or colour portable pixmap, .pgm or .ppm.
  477.  
  478.   -step <XxY>
  479.       gives the steps sisgen uses to traverse the depth map. (1x1)
  480.  
  481.       The technique for making a stereogram from a depth map involves inter-
  482.       preting the map as a very fine rectangular net then projecting this to
  483.       two buffers.
  484.  
  485.       This method is quite slow for large depth maps, so to speed up the pro-
  486.       cess the net is made coarser by skipping intervening points in both the
  487.       x and y directions.
  488.  
  489.       For example, "-step 2x3" means sisgen uses only alternate values in the
  490.       x direction and every third value in the y direction.
  491.  
  492.   -RANDOM <0-2>
  493.       specifies which type of random tile to generate. (0)
  494.  
  495.       There are three kinds of random tiles: 0) black & white; 1) grey-scale;
  496.       and 2) colour using a rainbow palette of 24 colours.
  497.  
  498.   -zblines <zb>
  499.       sets the number of lines that each z-buffer will use, see xpgs(6).
  500.       (256)
  501.  
  502.   -DENSITY <0-255>
  503.       sets the density of black dots in the SIRDS. (127)
  504.  
  505.   -help
  506.       prints a summary of command line options and returns to DCL.
  507.  
  508.   Once running, it will load the input file, display a few parameters,
  509.   request a filename (if one was not specified) and save the SIS. If sisgen
  510.   is in the pipe mode then it just loads in the file(s) and sends the result
  511.   down stdout. An example of using the pipe mode is "sisgen -o foo.xss | xv
  512.   -".
  513.  
  514. FILES
  515.  
  516. BUGS
  517.  
  518.   If you find any bugs, please report them to the author listed below.
  519.  
  520. SEE ALSO
  521.  
  522.   cvtopolyh(6), cvtoppm(6), mkpolyh(6), sisgen(6), vpgs(6), xpgs(6) and
  523.   xss(6).
  524.  
  525. AUTHOR, COPYRIGHTS, AND WARNINGS
  526.  
  527.   Copyright 1994, 16th November.
  528.   By Peter Chang. All rights reserved.
  529.   peterc@v2.ph.man.ac.uk
  530.   Version 1.0
  531.  
  532. =============================================================================
  533.  
  534. cvtoppm(6)                               cvtoppm(6)
  535.  
  536. NAME
  537.   cvtoppm - a program to generate depth maps and convert MindImage's rle
  538.   files to pgm and ppm formats
  539.  
  540. SYNTAX
  541.  
  542.   cvtoppm [options] <input file> [output p*m file]
  543.  
  544. DESCRIPTION
  545.   Cvtoppm is a utility with several functions. Primarily, it generates depth
  546.   maps from 3D datasets such as those given in .polyh and and rescaling old
  547.   depth maps. All output is in one of the portable pixmap formats, chosen by
  548.   the user.
  549.  
  550.   The main purpose of this program is to allow those feeling artistic to
  551.   create and amend a depth map with a paint package.  The result can be
  552.   viewed as a SIRDS or SIS using vpgs or sisgen.
  553.  
  554.   The depth map output is either a grey-scale (.pgm) or colour (.ppm) image.
  555.   Normally, the format used has an intensity value in the range 0-255 (for
  556.   colour, three values are used in each pixel) this limits the depth resolu-
  557.   tion to 256 (or 16777216) levels. This limitation can be altered with a
  558.   switch but the disadvantage is that the resultant file will be rather
  559.   large. [Technically, when zmax is less than 256 the PBM raw formats are
  560.   used instead of the ASCII formats.] Also unless the computer display you
  561.   are using can cope with a lot more than 256 colours, editing the depth maps
  562.   is fraught with difficulties. That is, you have to have at least 24bit
  563.   colour to manipulate continuous colour images.
  564.  
  565.   It takes at least one filename (or a switch to use stdin) and optional
  566.   switches as its command line arguments.
  567.  
  568.   Options
  569.  
  570.  
  571.   All these options can be abbreviated to the least letters needed to make
  572.   the chosen option distinct.  The default values are given in parentheses.
  573.  
  574.   -geometry <wxh>
  575.       sets the picture geometry, this defaults to the values given if the
  576.       input is 3D data otherwise it defaults to the depth map size. (320x198)
  577.  
  578.   -background <b>
  579.       sets the background plane at z=b*OY. (-1.0)
  580.  
  581.   -enlarge <ef>
  582.       specifies the enlargement of z coordinate . (1.0)
  583.  
  584.   -mag <mf>
  585.       sets the magnification of the scene, only applies to 3D data. (1.0)
  586.  
  587.   -pmm <res>
  588.       sets the dots' resolution in units of pixels per millimetre. (4.0)
  589.  
  590.   -zmax <zm>
  591.       sets the maximum value of each primary colour to be used in saving a
  592.       .ppm file or the number of greys in a .pgm file. (255)
  593.  
  594.   -colour
  595.       specifies that the output file will be a colour one.
  596.  
  597.   -xss
  598.       signifies that the input file contains 3D data and is either an .xss or
  599.       a .polyh file. This is the default.
  600.  
  601.   -dmap
  602.       signifies that the input file contains a depth map and is a grey-scale
  603.       or colour portable pixmap, .pgm or .ppm.
  604.  
  605.   -mind
  606.       signifies that the input file contains a rle depth map generated by
  607.       MindImage.
  608.  
  609.   -zblines <zb>
  610.       sets the number of lines that each z-buffer will use, see xpgs(6).
  611.       (256)
  612.  
  613.   -help
  614.       prints a summary of command line options and returns to DCL.
  615.  
  616.   Once running, it will decide on the operations to perform solely on the
  617.   command line switches.
  618.  
  619.  
  620. FILES
  621.  
  622. BUGS
  623.  
  624.   If you find any bugs, please report them to the author listed below.
  625.  
  626. SEE ALSO
  627.  
  628.   cvtopolyh(6), cvtoppm(6), mkpolyh(6), sisgen(6), vpgs(6), xpgs(6) and
  629.   xss(6).
  630.  
  631. AUTHOR, COPYRIGHTS, AND WARNINGS
  632.  
  633.   Copyright 1994, 16th November.
  634.   By Peter Chang. All rights reserved.
  635.   peterc@v2.ph.man.ac.uk
  636.   Version 1.0
  637.  
  638. =============================================================================
  639.  
  640. xss(6)                                       xss(6)
  641.  
  642. NAME
  643.   xss - a scene setter for the X Window System, using polyh data
  644.  
  645. SYNTAX
  646.  
  647.   xss [options] <polyh or xss file>
  648.  
  649. DESCRIPTION
  650.   Xss is an X11 program that displays and manipulates wireframe objects.  It
  651.   takes a .polyh or .xss file as input and optional switches as its command
  652.   line arguments.
  653.  
  654.   Options
  655.  
  656.  
  657.   All these options can be abbreviated to the least letters needed to make
  658.   the chosen option distinct.
  659.  
  660.   -display <display>
  661.       sets the X display name. By default it is the local host or that one
  662.       defined in the logical DECW$DISPLAY.
  663.  
  664.   -geometry <geometry>
  665.       sets the X geometry. (770x476 or 720x445)
  666.  
  667.   -fontname <name>
  668.       uses the font described by the name. The default is the fixed font.
  669.  
  670.   Once running, it will display a few parameters and some help messages in
  671.   the terminal window and create a graphics window with a wireframe model of
  672.   objects given by the input file.
  673.  
  674.   CONCEPTS
  675.  
  676.  
  677.   In xss, the three Cartesian axes are taken to be aligned horizontal (x -
  678.   positive to the right), vertical (y - positive upward) and normal (z -
  679.   positive toward the viewer) to the viewer.
  680.  
  681.   There are four modes in xss. Three object modes - rotation, scaling and
  682.   translation - and a rotation axis mode.
  683.  
  684.   In the object modes, the current object is drawn in solid lines whilst the
  685.   other objects are drawn in dashed lines. The current object can be rotated,
  686.   translated, magnified or shrunk using either the keys specified below or
  687.   the control panel. Additional objects and scenes can be loaded in and
  688.   objects can be cloned or deleted as well.
  689.  
  690.   In the rotation axis mode, a line appears which can be oriented in any
  691.   direction. The line shows the rotation axis that will be used in xpgs.  It
  692.   is made of two halves, each drawn differently. The solid half is the north-
  693.   ern part of the axis, the dashed half is the southern part. The rotation is
  694.   defined to be clockwise as you look along the axis from the south pole
  695.   northward.
  696.  
  697.   Once satisfied with the scene you have composed, the configuration can be
  698.   saved as a .xss file for use in xpgs, cvtoppm and sisgen.
  699.  
  700. GRAPHICAL USER INTERFACE
  701.  
  702.   Xss has a rather primitive user interface, partly because I haven't got
  703.   round to learning to use Xt and some widget set.
  704.  
  705.   WINDOW LAYOUT
  706.  
  707.  
  708.   There are two persistent windows in xss: the main graphics window and the
  709.   control panel. The main window shows, on startup, four subwindows:
  710.  
  711.      -----------------------------------
  712.      |             |           |
  713.      |    ----> x         |           |
  714.      |    |         |           |
  715.      |    |         |           |
  716.      |    v         |           |
  717.      |    z         |           |
  718.      |-------------------|-------------|
  719.      |    y         |        y  |
  720.      |    ^         |        ^  |
  721.      |    |         |        |  |
  722.      |    |         |        |  |
  723.      |    ----> x         |    z <----  |
  724.      |             |           |
  725.      -----------------------------------
  726.  
  727.  
  728.   The top right subwindow contains some information about the program, the
  729.   .xss file name and the current object. The other subwindows display the
  730.   three orthographic views (third angle projections?) which are front, right
  731.   end and plan.
  732.  
  733.   The objects can be drawn as wireframe figures or bounding boxes, with or
  734.   without clipping. The clipping in the orthographic scheme is separately
  735.   done in each view at the x=0, y=0 or z=0 plane.
  736.  
  737.   The projection scheme be changed to a perspective one. In this scheme,
  738.   there is only one view and hence only one window (no subwindows).  Also
  739.   clipping is done at the z=0 plane.
  740.  
  741.   Both persistent windows are sensitive to key presses - as long as the cur-
  742.   sor (or mouse pointer) is within their boundaries. See below for the keys.
  743.  
  744.   Using the mouse in the main window is limited to popping up the help window
  745.   which contains a reminder of the keys and their functions.
  746.  
  747.   The control panel is where the mouse actions are most useful. This panel is
  748.   divided into two types of mouse sensitive regions: the buttons and the
  749.   mouse pad.
  750.  
  751.   DIALOGUE POPUPS
  752.  
  753.   When any user text input is required - for instance when a file name to
  754.   save to - a dialogue window pops up at the pointer location.
  755.  
  756.   The popup window has three buttons which perform the following functions:
  757.  
  758.     OK  returns the text.
  759.     Clear
  760.         clears all text from the input field.
  761.     Cancel
  762.         returns without any text and cancels the operation which prompted
  763.         popup.
  764.  
  765.  
  766.   A number of keys are defined to facilitate editing (most a la emacs, hmm is
  767.   that correct French?):
  768.  
  769.     Left & Right cursor keys, ^B
  770.         moves the cursor along the text.
  771.     ^A & ^E
  772.         moves the cursor to the beginning and end of the text.
  773.     Backspace, Delete & ^H
  774.         deletes the character to the immediate left of the cursor.
  775.     Enter, Linefeed & Keypad Enter
  776.         finishes and commits the input text.
  777.     Escape
  778.         cancels the input.
  779.     ^D  deletes the character under the cursor.
  780.     ^U  deletes all the text from the beginning of the line to just left
  781.         of the cursor.
  782.     ^C  clears the text field.
  783.  
  784.   The pointer can also be used to move the text cursor: position the pointer
  785.   to where you want the cursor to be then click one of the mouse buttons and
  786.   release.
  787.  
  788.   The dialogue popup also appears in vpgs and xpgs.
  789.  
  790.   PANEL BUTTONS
  791.  
  792.  
  793.   All buttons in the control panel are of the press and release variety.  If
  794.   you press button one of the mouse (usually the left button) in the "Clip"
  795.   box and release whilst the pointer is still in that box then the action
  796.   corresponding to "Clip" is performed.
  797.  
  798.   Most buttons are single action devices but others are toggles which indi-
  799.   cate the state of the program.
  800.  
  801.     Quit
  802.         quits the program.
  803.  
  804.     Write Bitmap
  805.         writes an X11 bitmap of the main window.
  806.  
  807.     Save xss
  808.         saves the whole scene as a .xss file.
  809.  
  810.     Merge
  811.         inserts an old scene from another .xss file.
  812.  
  813.     Load
  814.         loads another object, i.e. .polyh file.
  815.  
  816.     Clone
  817.         replicates the current object.
  818.  
  819.     Delete
  820.         removes the current object.
  821.  
  822.     Other
  823.         moves to another object.
  824.  
  825.     Initialise
  826.         re-initialises the current object.
  827.  
  828.     Translate/Turn/Magnify/Axis
  829.         puts xss into the translate/turn/magnify/axis mode.
  830.  
  831.     Clip
  832.         switches on the clipping.
  833.  
  834.     Projection
  835.         changes the projection scheme.
  836.  
  837.     B Box
  838.         toggles the visibility of the bounding box of the current object.
  839.  
  840.     - Mag +
  841.         shrinks or magnifies the current object.
  842.  
  843.   MOUSE PAD
  844.  
  845.   This is the large box on the bottom of the control panel containing several
  846.   small squares and some line drawings.
  847.  
  848.   It has two appearances depending on the state of xss: a rotating state or a
  849.   linear state. The rotating state is shown by a dashed sphere with three
  850.   arrowed great circles and occurs when xss expects the action on the current
  851.   object (or axis) to be a rotation. The linear state is depicted by a set of
  852.   three arrowed mutually perpendicular axes and occurs when the anticipated
  853.   action is a translation or scaling.
  854.  
  855.   The line graphics are an isometric view of the sphere or the triad of axes
  856.   with x and y directions going horizontally and vertically, respectively and
  857.   the z direction, from positive to negative, goes from bottom left diago-
  858.   nally across to top right.
  859.  
  860.   The square boxes within the mouse pad indicate the areas that are sensitive
  861.   to mouse presses. Their positions in the mouse pad, in relation to the
  862.   arrowed lines and curves, indicate the action to be taken when pressed.
  863.   For example, in the rotating state, the rightmost square is configured to
  864.   rotate the current object clockwise as it faces the viewer; in the linear
  865.   state it is configured to translate the object right or magnify it horizon-
  866.   tally.
  867.  
  868.   The squares allow a click, hold, drag and release methodology (ugh).    The
  869.   further the pointer is released from the centre of the square it had click
  870.   on, the more an action is performed - provided the pointer is released
  871.   within the boundary of the mouse pad. As an aid, circles are drawn to help
  872.   the user to gauge the magnitude of their action, they indicate the number
  873.   of times a transformation will be performed.
  874.  
  875.   MOUSE BUTTONS
  876.  
  877.  
  878.   The third (usually the right) mouse button acts like the first button but
  879.   in actions where transformations are made, its effects are fivefold.    The
  880.   shift key can also be used in conjunction with the first mouse button to
  881.   act like the third.
  882.  
  883.   KEYS
  884.  
  885.  
  886.   With the mouse pointer within the boundaries of the graphics window, xss
  887.   will respond to a set of keypresses.
  888.  
  889.     q   quits the program.
  890.     h   pops up a help window.
  891.     w   saves the main window as an X11 bitmap.
  892.     s   saves the whole scene as a .xss file.
  893.     f   inserts an old scene from another .xss file.
  894.     r   replicates the current object.
  895.     l   loads another object, i.e. .polyh file.
  896.     d   deletes the current object.
  897.     o   moves to another object.
  898.     i   re-initialises the current object.
  899.     b   toggles the bounding box of the current object.
  900.     c   un/clips the current object at the z=0 plane, rendering the por-
  901.         tion below z=0 invisible. This function is to aid depth percep-
  902.         tion.
  903.     p   change the projection scheme from three orthographic views to one
  904.         perspective view, or vice versa.
  905.     m   magnifies the current object.
  906.     n   shrinks the current object.
  907.     t   toggles the between the turn, magnify and translate modes.
  908.     a   toggles the rotation axis definition mode.
  909.     v   toggles the verbosity of the program.
  910.     SHIFT (the shift keys)
  911.         toggles the magnitude of the changes. Holding down the shift key
  912.         makes all subsequent changes relatively coarse (by a factor of
  913.         five) and releasing it reverts to finer changes.
  914.  
  915.     The manipulation keys are the cursor keys, the greater-than (or full
  916.     stop or period) key and the less-than (or comma) key.  They change
  917.     the objects in a visually obvious way.
  918.  
  919.     In rotation mode, (+ means clockwise about positive axis)
  920.         x axis: - Up   + Down
  921.         y axis: - Left + Right
  922.         z axis: + <,   - >.
  923.  
  924.     In translation mode,
  925.         x axis: - Left + Right
  926.         y axis: + Up   - Down
  927.         z axis: + <,   -  >.
  928.  
  929.     In the rotation axis definition mode, the manipulations keys perform
  930.     similar tasks to the rotation mode.
  931.  
  932. BUILT-IN OBJECTS
  933.  
  934.   A number of builtin objects are now available. To access them, press the
  935.   "l" key or "Load" button and type in a name (with parameters) instead of a
  936.   .polyh file.
  937.  
  938.   The following primitives are available:
  939.  
  940.     polygon(pdiv, pbeg, pend, chord)
  941.         a polygon in the x-y plane, made from a regular polygon of pdiv
  942.         sides (3) and starts at the vertex pbeg (0) and ends at vertex
  943.         pend (pdiv).  If chord (0) is 0 then the polygon is closed with
  944.         lines from the ends to the centre, otherwise a line joins the
  945.         ends directly.
  946.  
  947.     pyramid(pdiv, pbeg, pend, chord)
  948.         a pyramid with a polygon base described by polygon(pdiv, pbeg,
  949.         pend, chord) and has an apex at (0,0,1).
  950.  
  951.     prism(pdiv, pbeg, pend, chord, zdiv, zno, lid)
  952.         a prism made from a polygon base that extends out in the positive
  953.         z direction to z=1. This is divided into zdiv (1) subsections and
  954.         the prism comprises zno (zdiv) of these. (If ano is greater than
  955.         adiv, then the shape is further extended.) If lid (1) is 0 then
  956.         the prism is not capped, otherwise it has end faces.
  957.  
  958.     spiral(pdiv, pbeg, pend, chord, xs, yinc, adiv, ano, lid)
  959.         a shape made from the extrusions of a polygon, shifted xs (2.0)
  960.         in the x direction, rotated about the y axis. It is     further
  961.         shifted smoothly so that it is displayed by yinc (0.0) in the y
  962.         direction every completed turn. This shell is divided into adiv
  963.         (36) subsections and the spiral is composed out of ano (adiv) of
  964.         these. (If ano is greater than adiv, then the shape is extruded
  965.         further.) If lid (0) is 0 then the spiral is not capped, other-
  966.         wise it has end faces.
  967.  
  968.   The numbers in parentheses shown the default values taken by the program.
  969.   When you use the primitives, you need not specify all the arguments, later
  970.   values can be omitted (a la C++).
  971.  
  972.   Also, there are a number of presets made from these primitives:
  973.  
  974.     triangle - an equilateral triangle
  975.     square     - a square
  976.     box     - a cube
  977.     cylinder - a right cylinder
  978.     cone     - a right cone
  979.     torus     - a torus or doughnut
  980.     sphere     - a ball
  981.     spring     - a thick helix
  982.  
  983.   You should taken care when using these builtin objects because the parser
  984.   is not too intelligent.
  985.  
  986. FILES
  987.  
  988. BUGS
  989.  
  990.   If you find any bugs, please report them to the author listed below.
  991.  
  992. SEE ALSO
  993.  
  994.   cvtopolyh(6), cvtoppm(6), mkpolyh(6), sisgen(6), vpgs(6), xpgs(6) and
  995.   xss(6).
  996.  
  997. AUTHOR, COPYRIGHTS, AND WARNINGS
  998.  
  999.   Copyright 1994, 16th November and 14th February.
  1000.   By Peter Chang. All rights reserved.
  1001.   peterc@v2.ph.man.ac.uk
  1002.   Version 2.0
  1003.  
  1004. =============================================================================
  1005.  
  1006. cvtopolyh(6)                             cvtopolyh(6)
  1007.  
  1008. NAME
  1009.   cvtopolyh - a program to convert various 3D data formats to the AVS polyh
  1010.   format
  1011.  
  1012. SYNTAX
  1013.  
  1014.   cvtopolyh <options> <object file> <polyh file>
  1015.  
  1016. DESCRIPTION
  1017.   Cvtopolyh is a program that loads in and converts various 3D object formats
  1018.   to the AVS .polyh format.
  1019.  
  1020.   A .polyh file contains a list of vertex coordinates and a list of polygonal
  1021.   faces given by indexed points. (There is a slight difference with AVS's
  1022.   definition with the inclusion of an optional comment line at the start of
  1023.   the file which begins with a hash "#".) A number of objects can be found at
  1024.   avalon.vislab.navy.mil or its mirrors.
  1025.  
  1026.   It takes two filenames and some switches as its command line arguments.
  1027.  
  1028.   Options
  1029.  
  1030.  
  1031.   The letter in brackets is optional and when specified centres the object.
  1032.  
  1033.   -p[c] loads a AVS .polyh file.
  1034.  
  1035.   -3[c] loads a certain .3ds file (3D Studio?).
  1036.  
  1037.   -b[c] loads the above type of file with an additional bounding box.
  1038.  
  1039.   -o[c] loads an X3d v2.0 .obj file.
  1040.  
  1041.   -w[c] loads a Wavefront .obj file.
  1042.  
  1043.   Once running, it will load in the data file, display a few parameters,
  1044.   check for redundant points, centre the object (if requested) and then nor-
  1045.   malise the object. After all this, the object is saved in .polyh format
  1046.   along with a comment.
  1047.  
  1048. FILES
  1049.  
  1050. BUGS
  1051.  
  1052.   If you find any bugs, please report them to the author listed below.
  1053.  
  1054. SEE ALSO
  1055.  
  1056.   cvtopolyh(6), cvtoppm(6), mkpolyh(6), sisgen(6), vpgs(6), xpgs(6) and
  1057.   xss(6).
  1058.  
  1059.  
  1060.  
  1061. AUTHOR, COPYRIGHTS, AND WARNINGS
  1062.  
  1063.   Copyright 1994 and 1995, 26th January.
  1064.   By Peter Chang
  1065.   peterc@a3.ph.man.ac.uk
  1066.  
  1067.   Version 2.1
  1068.  
  1069. =============================================================================
  1070.  
  1071. mkpolyh(6)                               mkpolyh(6)
  1072.  
  1073. NAME
  1074.   mkpolyh - a program to generate rectangular meshes or nets from given func-
  1075.   tions
  1076.  
  1077. SYNTAX
  1078.  
  1079.   mkpolyh [options] <output file>
  1080.  
  1081. DESCRIPTION
  1082.   Mkpolyh is a utility to create meshes from one of several mesh functions,
  1083.   of the form z = f(x,y). The data is saved as a .polyh file.
  1084.  
  1085.   The main purpose of this program is to allow the user to write their own
  1086.   mesh function and create a mesh for personal use. There are a number of
  1087.   sample functions included in the source code meshfn.c to demonstrate how to
  1088.   implement a mesh function.
  1089.  
  1090.   It takes one filename and optional switches its command line arguments.
  1091.  
  1092.   Options
  1093.  
  1094.  
  1095.   All these options can be abbreviated to the least letters needed to make
  1096.   the chosen option distinct.  The default values are given in parentheses.
  1097.  
  1098.   -list
  1099.       lists the functions available with their default settings.
  1100.  
  1101.   -function <fno>
  1102.       sets the mesh function to be used. (0)
  1103.  
  1104.   -size <XxYxZ>
  1105.       specifies the size of the bounding box. (1.0x1.0x1.0)
  1106.  
  1107.   -divisions <XxY>
  1108.       sets the number of divisions used in the gird. (30x30)
  1109.  
  1110.   -dmap '(<p1>,[<p2>,...])'
  1111.       gives the parameters for the chosen function to use.
  1112.  
  1113.   -help
  1114.       prints a summary of command line options and returns to DCL.
  1115.  
  1116.   Once running, it will decide on the operations to perform solely on the
  1117.   command line switches.
  1118.  
  1119.  
  1120. FILES
  1121.   meshfn.c - the source code containing the mesh functions.
  1122.  
  1123.  
  1124.  
  1125.  
  1126. BUGS
  1127.  
  1128.   If you find any bugs, please report them to the author listed below.
  1129.  
  1130.  
  1131.  
  1132. SEE ALSO
  1133.  
  1134.   cvtopolyh(6), cvtoppm(6), mkpolyh(6), sisgen(6), vpgs(6), xpgs(6) and
  1135.   xss(6).
  1136.  
  1137. AUTHOR, COPYRIGHTS, AND WARNINGS
  1138.  
  1139.   Copyright 1994, 16th November.
  1140.   By Peter Chang. All rights reserved.
  1141.   peterc@v2.ph.man.ac.uk
  1142.   Version 1.0
  1143.  
  1144. =============================================================================
  1145.